home *** CD-ROM | disk | FTP | other *** search
/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-02 / scan200a.zip / SCANHELP.DOC < prev    next >
Text File  |  1991-12-01  |  12KB  |  277 lines
  1. SCANHELP - Utility to produce help files from TP source code.
  2.  
  3. Version 2.00Alpha - test version of update by D.J. Murdoch to
  4. TurboPower's utility.
  5.  
  6. This update is copyright (1991) D.J. Murdoch.  When finalized, I intend
  7. to release it to the public domain, as TurboPower released the original
  8. SCANHELP. Until then, I'd like to keep control of it, so this release is
  9. *not* public domain.
  10.  
  11. REQUIREMENTS
  12.  
  13. SCANHELP produces *.TXT files suitable for input to the TurboPower
  14. MakeHelp utility.  This utility comes with TurboPower's Turbo
  15. Professional and Object Professional packages; if you don't have one of
  16. those, SCANHELP isn't going to help you.
  17.  
  18. AIMS
  19.  
  20. SCANHELP was one of TurboPower's Help Tools, released to the public
  21. domain in January 1990.  It was designed to create an outline for a help
  22. database describing the interface to a Turbo Pascal unit; the assumption
  23. was that the user would make major modifications to the outline to
  24. produce a polished help system.
  25.  
  26. I wanted something different:  I wanted documentation for myself, and I
  27. wanted it to be easy to produce.  I've found that it's too easy for
  28. printed documentation to get out of synch with the source code when the
  29. code is under development; even my online documentation kept falling
  30. behind, because it was just too much trouble to go to the *.TXT file and
  31. correct the documentation when I made a small change.
  32.  
  33. The design aim for SCANHELP 2 is thus to produce complete *.TXT files,
  34. suitable for input to MAKEHELP.  These should be good enough for
  35. internal use without any manual editing.  It should be possible to
  36. customize them by working within the original *.PAS source code;
  37. duplicate documentation should not be necessary.
  38.  
  39. Some other things I've attempted to do, with varying success:
  40.  - produce documentation for *every* interfaced symbol
  41.  - have a minimal impact on the source code, i.e. existing source code
  42.    should produce reasonable help files without substantial changes
  43.  - handle multiple source files, so cross references to other units are
  44.    possible
  45.  - work with Pascal scoping rules, so that cross references are easy.
  46.  
  47. THIS IS A TEST VERSION!
  48.  
  49. This version of SCANHELP is far from complete.  I'm releasing it because
  50. I'd like to get other people's suggestions for useful features.
  51. If you try it out, *please* send me a message saying what you like about
  52. it and what you dislike, and let me know of any gross bugs.  (There are
  53. lots of minor bugs; I'm not going to worry about those, until the design
  54. stabilizes.)
  55.  
  56. Things I'd especially like to hear:
  57.  
  58.  - suggestions for different displays.  Do you violently dislike the way
  59.    SCANHELP displays variant records?  How would you do it?
  60.  - suggestions for essential command line options.  I haven't worked on
  61.    those yet; what sort of options would you like?  Please suggest
  62.    syntax.
  63.  - suggestions for new comment directives.  I've only added #T (see
  64.    below) to the original SCANHELP directives; what other ones would be
  65.    really useful?
  66.  
  67. Please send comments to me (Duncan Murdoch) at one of the following addresses:
  68.  
  69.   Fidonet:    DJ Murdoch at 1:163/140.3 (1:221/177.40 starting January 92)
  70.   Internet:   dmurdoch@watstat.waterloo.edu
  71.   Compuserve: 71631,122
  72.  
  73. DOCUMENTATION
  74.  
  75. Below is an extract from TurboPower's documentation for the Help
  76. Utilities.  I've marked changes with "!!".
  77.  
  78. SCANHELP
  79. -----------------------------------------------------------------------------
  80. SCANHELP is used to creating help systems for program libraries (like
  81. Object Professional or B-Tree Filer). The input is one or more Turbo Pascal
  82. source code files; the output is corresponding help text files.
  83.  
  84. SCANHELP creates help topics for each interfaced object, method,
  85. procedure, function !!or other identifier!! in a program.  The help
  86. topic consists of an automatically assigned topic number, the object or
  87. routine declaration, and a 'See also' section of cross-references.
  88.  
  89. A "See also" list can also be created after each topic. SCANHELP has some
  90. fixed logic for formatting this list. First, it tries to put all of your
  91. cross-references, separated by two spaces each, onto one line prefaced by See
  92. also:. If the cross-references won't fit, SCANHELP writes a blank See also
  93. line, then builds a two or three column table under that line. The number of
  94. columns is controlled by a command line option (the default is three columns).
  95. This can be overridden by a directive in your source code (more on these
  96. directives later).
  97.  
  98. SCANHELP assumes a text width of 76 characters. It includes such a command at
  99. the top of the first output file; and, it prevents cross-reference topics from
  100. extending beyond that column.
  101.  
  102. The "See also" tag is !! only written if there are cross references
  103. defined.!!
  104.  
  105. SCANHELP also creates a topic entry for the unit itself. This is always the
  106. first topic it creates and it contains the unit name and !! categorized
  107. tables of all identifiers with global scope.  Separate lists of
  108. constants, types, variables, and functions/procedures are given.!!
  109.  
  110. This is the only topic that doesn't have a !NOINDEX command after it so it is
  111. the only topic that will show up in a help index.
  112.  
  113. SCANHELP Directives
  114. -------------------
  115. SCANHELP has several directives for customizing its behavior. A directive is
  116. something that you place in the source code before running SCANHELP.
  117.  
  118. All directives have the format {#L...} where:
  119.   {  }   are normal comment braces
  120.   #      signals that this is a SCANHELP directive
  121.   L      is a command letter
  122.   ...    are one or more parameters for the directive
  123.  
  124. #Z+ / #Z-   Toggle Private
  125.   This directive controls what symbols are included in the help text. The
  126.   default is all interfaced objects, methods, procedures and functions. If you
  127.   want to exclude one or more these symbols, then place a {#Z+} directive in
  128.   front of them and a {#Z-} directive following. The Z+ signals that all
  129.   following symbols are private and should not be included in the help text.
  130.   The Z- turns off the "private" attribute.
  131.  
  132. #X [Object.]Topic [[Object.]Topic...]  Include cross-reference
  133.   This directive specifies that Topic is to be included in the "See also" list
  134.   for the current symbol.
  135.  
  136.   If the topic is an ambigous method name (like Init or Done), you can
  137.   optionally include the [Object.] prefix to resolve the ambiguity. Note that
  138.   the _only_ time the [Object.] prefix is required is when the
  139.   cross-referenced method belongs to a different object, but has the same name
  140.   as a method in the current object.
  141.  
  142.   You can have as many topics in one #X directive as you like. Or, you can
  143.   specify multiple #X directives.  For example, the following are equivalent:
  144.  
  145.     {#X TopicA TopicB TopicC}
  146.  
  147.   and
  148.  
  149.     {#X TopicA}
  150.     {#X TopicB}
  151.     {#X TopicC}
  152.  
  153. !!  In order to resolve cross references, Pascal scoping rules are used.
  154. If you have two identifers named TopicA, then the one which is in scope
  155. will be referenced.  You can override the default using the dot syntax,
  156. Scope.TopicA.  You can make references to topics in other units,
  157. provided that the other source file is being scanned in the same run of
  158. SCANHELP.  If the other unit is one that is being Use'd in your unit, no
  159. unit override will be necessary.!!
  160.  
  161. #C2 / #C3 Column count
  162.   This directive overrides the global column count (for the See also table)
  163.   for the current object. You would use this directive for occasional
  164.   deviations from the global column count. That is, if you specified a global
  165.   column count of three, but you have a couple of very long topic names, you
  166.   may want to specify #C2 whenever those long topic names are included in a
  167.   See also list.
  168.  
  169. #T Topic [comment]
  170.   This directive creates a new topic and a new identifier in the current
  171.   scope.  SCANHELP parses it as a new declaration; it'll be a syntax
  172.   error to put this kind of comment directive in the middle of another
  173.   one.  For example:
  174.  
  175.     type Myrec = record
  176.       { this comment will go into the Myrec topic }
  177.       a : word;
  178.       { this comment will go into the Myrec.a topic }
  179.       {#T about_myrec}
  180.       { this comment will go into a Myrec.about_myrec topic }
  181.       b : word;
  182.       { this comment will go into the Myrec.b topic, with cross
  183.       references to the other two topics. }
  184.       {#X about_myrec a}
  185.     end;
  186.  
  187.   You can use #X directives after #T; this will create See Also entries
  188.   in the #T topic.  Other #X directives can refer to the #T topic, using
  189.   the topic name, as shown after the Myrec.b comment above.
  190.  
  191. !!
  192.  
  193. SCANHELP Command line options:
  194. ------------------------------
  195. Some of SCANHELP's behavior is customized from the command line. Here is the
  196. command line format:
  197.  
  198.   SCANHELP [options] unitname [unitname...]
  199.  
  200. Here is a description of SCANHELP's options:
  201.  
  202.   /N    don't show the comment after each symbol declaration
  203.  
  204. The default is for one comment immediately following a symbol declaration to
  205. be included as the text for that help topic. If you don't want this, specify
  206. the /N option. (SCANHELP does some minor reformatting to this comment: it
  207. removes the comment braces and adds a discretionary period at the end.)
  208.  
  209.   /T startingtopic  specify the starting topic number
  210.  
  211. The default starting topic number is one. If you want to start at a different
  212. number, use the /T option.
  213.  
  214.   /I topicinc  specify the topic increment value
  215.  
  216. The default topic increment value is one. That is, topics are numbered
  217. sequentially, without gaps, from the starting topic number. If you want gaps
  218. between your topic numbers, specify the increment here.
  219.  
  220.   /2  use 2 columns for "See also" tables
  221.  
  222. The default number of columns is three. If you want to change this for all
  223. topics, use the /2 option. If you only want to change it for a few topics,
  224. use the #C2 option within your source file.
  225.  
  226.   /S  sort cross-references
  227.  
  228. The default behavior for the cross-reference table (the See also's) is to
  229. present the cross-references in the same order they appear in the #X
  230. directives in the source code. This gives you complete control over the format
  231. of the table. Where you are not interested in any particular topic order,
  232. you'll probably want to sort the table with /S.
  233.  
  234.   /F fileinc  specify the between-file increment value
  235.  
  236. SCANHELP can process multiple files at once. The default is to make the topic
  237. numbers contiguous between files. This isn't desirable if you intend to
  238. manually add some help topics to the text file. Use the /F option to specify a
  239. gap to leave between files.
  240.  
  241.   /D  Don't wrap the procedure/function declarations
  242.  
  243. !!  This directive is currently inoperative! !!
  244.  
  245. When word-wrapping is on, long procedure/function declarations may fall victim
  246. to wrapping (if they extend beyond column 74). Remember that SCANHELP inserts
  247. the object or unit name into every declaration. That means that declarations
  248. that are less than 74 characters in the source code may be expanded beyond
  249. that in the final help file. Using the /D option will surround all
  250. declarations with !NOWRAP / !WRAP commands to prevent wrapping. The
  251. negative effect of this is that your declarations may now extend slightly
  252. beyond the viewing area of the help window. The best solution is to modify the
  253. source code and make sure that all declarations are short enough to fit
  254. without being word-wrapped.
  255.  
  256. SCANHELP Process
  257. ----------------
  258. So, putting this all together, the standard process for creating a help text
  259. is as follows:
  260.  
  261.   1. Annotate source listings with # directives
  262.   2. Run SCANHELP on all files (wildcards ok)
  263.   3. Build a "main file" with !INCLUDE statements for the newly created
  264.      help text files.
  265.  
  266.  
  267. Change History
  268. --------------
  269. 1.01  10-8-90
  270.       SCANHELP - Changed .Z to #Z to agree with documentation
  271.  
  272. 1.02  3-7-91
  273.       SCANHELP - Fixed "xref line too long" bug
  274.  
  275. 2.00  1-Dec-91
  276.       SCANHELP - Major changes by DJM.
  277.